Implement dwell timers #465

belleklaviyo · 2025-11-26T21:31:00Z

Description

Easiest to review commit by commit but basically --

iOS does not have native support for dwell events. Instead, we can only go off of didEnter/didExit events and tracking potential dwell events via timers and do our best to catch if they have expired or not.

If a geofence has a duration on it, we start a timer for the given duration when the user triggers an enter event for that geofence. If the timer is still around when the timer expires, we fire a dwell event knowing an exit event has not occurred to cancel it.
If a user entered a geofence and exited it before a certain duration, then we cancel the dwell timer and know a dwell event has not occurred.

These timers are stored in memory.

Tricky part is, timers only run while the app is in the foreground. So, here is where we start doing a best-effort to catch expired dwell timers by also persisting their time stamps to UserDefaults

We check if any dwell timers have expired in the following cases when the app + network is available: foreground events, background events, and when a geofence event wakes up the app from a terminated state.
If any dwell timers have expired (their timestamp + duration has passed compared to the current time) when we check, then we fire a dwell event. In these cases, there will be a bit of a delay/inaccuracy of the event time as we only caught it when we could.

Due Diligence

I have tested this on a simulator or a physical device.
I have added sufficient unit/integration tests of my changes.
I have adjusted or added new test cases to team test docs, if applicable.
I am confident these changes are compatible with all iOS and XCode versions the SDK currently supports.

Release/Versioning Considerations

Patch Contains internal changes or backwards-compatible bug fixes.
Minor Contains changes to the public API.
Major Contains breaking changes.
Contains readme or migration guide changes.
- If so, please merge to a feature branch so documentation updates only go live upon official release.
This is planned work for an upcoming release.
- If no, author or reviewer should account for this in a release plan, or describe why not below.

Changelog / Code Overview

Test Plan

I used a mocked response for GET client/geofences in this commit to test getting a geofence response with durations. I then tested all of the following scenarios and some other variants:

App was foregrounded when enter event happened, then waited the expected duration, and then saw a dwell event fire.
App was foregrounded when enter event happened and backgrounded halfway through duration period. App was in background for remainder of duration period (and a bit beyond). Dwell event did not fire automatically. Upon reforegrounding, though, dwell event fired.
App was backgrounded when enter event happened and terminated halfway through duration period. App was in terminated for remainder of duration period (and a bit beyond). Location was changed "significantly" while app still terminated (waking up app). Dwell event fired without app being opened.

Related Issues/Tickets

https://klaviyo.atlassian.net/browse/CHNL-28037

* Initialize on geofence event * Add tests to check priority insertion, instant flush, and init effect * guard against empty companyIds form malformed geofences * Reject geofence events if they have a mismatching API key to the one in store

…nd, awake on geo event

Sources/KlaviyoLocation/Utilities/DwellTimerTracker.swift

Sources/KlaviyoLocation/KlaviyoLocationManager.swift

… more clear separation

Sources/KlaviyoLocation/KlaviyoLocationManager+CLLocationManagerDelegate.swift

…eEvent call

Sources/KlaviyoLocation/KlaviyoLocationManager+CLLocationManagerDelegate.swift

Sources/KlaviyoLocation/Models/Geofence.swift

ajaysubra · 2025-12-03T17:05:39Z

App was foregrounded when enter event happened and backgrounded halfway through duration period. App was in background for remainder of duration period (and a bit beyond). Dwell event did not fire automatically. Upon reforegrounding, though, dwell event fired.

Firstly, thanks for the detailed notes on the PR. Super useful for reviewing. If we should fire the dwell event in the future seemed to me like a product question so checking in with PMs.

ab1470

looks good, although it seems like maybe we're not going to merge this?

ab1470 · 2025-12-03T22:08:23Z

Sources/KlaviyoLocation/Models/Geofence.swift

+    /// Optional duration for this geofence to record a dwell event
+    var duration: Int? {
+        let components = id.split(separator: ":", omittingEmptySubsequences: false)
+        guard components.count == 4, components[0] == "_k" else { return nil }


didn't we have an isKlaviyo... method somewhere to check if something starts with _k (and therefore is a Klaviyo event/notification)?

ab1470 · 2025-12-03T22:16:09Z

Sources/KlaviyoLocation/KlaviyoLocationManager.swift

+        geofenceDwellSettings.removeAll()
+        for geofence in geofences {
+            geofenceDwellSettings[geofence.locationId] = geofence.duration
+        }


This code will remove all geofence dwell settings, including those that may not have been included in the Set that the caller supplied when they called this method. Is that okay?

ab1470 · 2025-12-03T22:37:42Z

Sources/KlaviyoLocation/KlaviyoLocationManager+CLLocationManagerDelegate.swift

+            if #available(iOS 14.0, *) {
+                Logger.geoservices.info("🕐 Fired expired dwell event for region \(geofenceId) (expired while app was terminated)")
+            }


I think this should go inside the Task, below the full await clause. Technically the current order is incorrect, as you're dispatching an async task that may or may not complete, and then you're immediately logging the event before waiting for the task to finish

ab1470 · 2025-12-03T23:10:01Z

Sources/KlaviyoLocation/Utilities/DwellTimerTracker.swift

            // Check if timer expired (elapsed >= duration)
-            if age >= TimeInterval(timerData.duration) {
-                timersToRemove.append(geofenceId)
+            if currentTime - timerData.startTime >= TimeInterval(timerData.duration) {


can you create a private helper function (or computed property) to abstract this logic and make it more readable? Something like:

if timerData.isExpired { ... }

belleklaviyo · 2025-12-05T15:11:08Z

Closing for now as we have decided due to iOS's limitations of not natively supporting dwell and consequently requiring intrusive/overly complex workarounds to even provide a best effort level of support, we will not support it for this milestone. We may revisit later and/or include some of these model changes, so we could flexibly support it in the future and be backwards compatible. If we decide to do those model changes/more incremental support, we will do those in new PRs.

belleklaviyo added 12 commits November 25, 2025 16:09

Initialize on geofence event (#460)

715ec05

* Initialize on geofence event * Add tests to check priority insertion, instant flush, and init effect * guard against empty companyIds form malformed geofences * Reject geofence events if they have a mismatching API key to the one in store

Add duration field to Geofence object

2d37272

Add dwell timers and dwell event firing

e771c52

Add mock stub (for now) to test duration

d6c726d

Create DwellTimerTracker for persistence

7fe48ad

Add checkExpiredDwellTimers func to fire dwell events

1fba188

add DwellTimerTracker to KlaviyoLocationManager

b24771b

Add and remove timers from DwellTimerTracker in lifecycle

6c0962f

Check and fire expired persisted dwell events on foreground, backgrou…

65fee38

…nd, awake on geo event

Rename some things for clarity

f99074c

Add tests

931c3eb

Restore real API call

72f2a2b

belleklaviyo marked this pull request as ready for review December 2, 2025 20:59

belleklaviyo requested review from a team as code owners December 2, 2025 20:59

klaviyoit requested review from ab1470 and kennyklaviyo December 2, 2025 20:59

belleklaviyo removed the request for review from kennyklaviyo December 2, 2025 21:05

cursor bot reviewed Dec 2, 2025

View reviewed changes

Sources/KlaviyoLocation/Utilities/DwellTimerTracker.swift Outdated Show resolved Hide resolved

Sources/KlaviyoLocation/KlaviyoLocationManager.swift Show resolved Hide resolved

Simplify getExpiredTimers to only concern itself with persisted ones,…

543fae4

… more clear separation

cursor bot reviewed Dec 2, 2025

View reviewed changes

Sources/KlaviyoLocation/KlaviyoLocationManager+CLLocationManagerDelegate.swift Show resolved Hide resolved

Sources/KlaviyoLocation/KlaviyoLocationManager+CLLocationManagerDelegate.swift Show resolved Hide resolved

belleklaviyo requested a review from ajaysubra December 3, 2025 15:03

belleklaviyo added 2 commits December 3, 2025 11:20

Modify DwellTimerData to contain apiKey to make correct createGeofenc…

6575fcc

…eEvent call

Invalidate tiemrs in memory if they fired from persistence

44a47de

cursor bot reviewed Dec 3, 2025

View reviewed changes

Sources/KlaviyoLocation/KlaviyoLocationManager+CLLocationManagerDelegate.swift Show resolved Hide resolved

Sources/KlaviyoLocation/Models/Geofence.swift Show resolved Hide resolved

ab1470 approved these changes Dec 3, 2025

View reviewed changes

belleklaviyo closed this Dec 5, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Implement dwell timers #465

Implement dwell timers #465

Uh oh!

belleklaviyo commented Nov 26, 2025 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ajaysubra commented Dec 3, 2025

Uh oh!

ab1470 left a comment

Uh oh!

ab1470 Dec 3, 2025

Uh oh!

ab1470 Dec 3, 2025

Uh oh!

ab1470 Dec 3, 2025

Uh oh!

ab1470 Dec 3, 2025

Uh oh!

belleklaviyo commented Dec 5, 2025 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Implement dwell timers #465

Implement dwell timers #465

Uh oh!

Conversation

belleklaviyo commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Due Diligence

Release/Versioning Considerations

Changelog / Code Overview

Test Plan

Related Issues/Tickets

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ajaysubra commented Dec 3, 2025

Uh oh!

ab1470 left a comment

Choose a reason for hiding this comment

Uh oh!

ab1470 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

ab1470 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

ab1470 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

ab1470 Dec 3, 2025

Choose a reason for hiding this comment

Uh oh!

belleklaviyo commented Dec 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

belleklaviyo commented Nov 26, 2025 •

edited

Loading

belleklaviyo commented Dec 5, 2025 •

edited

Loading